Video Descriptors Taxonomy Endpoint
Video Descriptors are a comprehensive data set of distinct descriptors that are bound by a unified Video Descriptor Taxonomy . These descriptors are optimized for search and discovery use cases. The data set is created by specially-trained Gracenote editors using a rigorous tagging process to ensure a high-quality and consistent metadata product. The Video Descriptors feature is sold separately. Contact your Gracenote representative to get this feature.
The Gracenote Video Descriptors Taxonomy (VDT) provides data to reconstruct a structured hierarchical relationship (parent/child tree) between descriptors. Taxonomy data is not very dynamic - the changes typically occur on a quarterly cadence and Gracenote usually distributes notifications about the taxonomy changes.
API and Example Responses
API
http://on-api.gracenote.com/v3/VideoDescriptorsTaxonomy
?updateId=[updateId value] &limit=[limit value] &api_key=[your-api-key]
Request Parameters
Important: Use lookup calls for QA and troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.
Example Requests
Return Video Descriptor Taxonomy data.
http://on-api.gracenote.com/v3/VideoDescriptorsTaxonomy?updateID=0&limit=7&api_key=<your-api-key>
Example Responses
See Video Descriptor Taxonomy XML examples
Accessing Video Descriptors
You must integrate with two data delivery endpoints to fully access and use the Video Descriptors data set in your application.
- The Video Descriptor Taxonomy endpoint, and
- Either the Programs endpoint or the Program Annotations endpoint.
To access hierarchically organized Video Descriptors data, use the standalone Video Descriptor Taxonomy endpoint. You must integrate with this endpoint for full Video Descriptors data access.
To access the Video Descriptors specifically tagged to Programs:
Programs endpoint (recommended for On API v3.x customers):
- Gracenote can enable the Video Descriptors block within the Programs XML based on your entitlements.
- You can access Video Descriptors tagged to Programs in the overall Programs context. More information is available in the Programs endpoint topic.
Program Annotations endpoint:
- If you prefer to access only the Video Descriptors data for a program at the TMSId level, use the standalone ProgramAnnotations endpoint.
- Using this endpoint, you can access the Video Descriptors without having to parse through other Program information (like Title, Cast, Images, Release etc.)
Video Descriptor Updates
Video descriptor updates are less frequent than other endpoints. It is anticipated that updates will happen quarterly, but may occur monthly if needed. You will be provided advanced notice of any upcoming taxonomy change.
Each Video Descriptor Taxonomy element is comprised of a single Type and its underlying keywords to simplify the referential integrity between versions. For example, if a Video Mood keyword ‘Serious’ is updated, you will receive all Video Mood keywords in the next update. Most updates are rolled into a single quarterly update for ease of processing. This means the update could contain simple label changes and/or changes to the hierarchy.
Types of changes that can be expected in the Video Descriptor Taxonomy include:
- New keyword added
- Keyword label change
- Keyword Delete
- Keyword parent change (Hierarchy change)
- New type addition with child keywords
When requesting updates, the most recent version of a video descriptor taxonomy is returned. Updates are not 'replayed' as a log of changes. For example, if a keyword label is modified once, and then modified again, the next call for updates includes the keywords from that type only once in the response, with latest updateId. For this reason, updateIds in a response are not consecutive, although video descriptor taxonomy output is sorted by updateId.
Video Descriptors Taxonomy Data Structure and Relationships
Schema
Review the following XML schema definition (xsd) to learn about the data structure, fields, and types for this endpoint.
To explore the relationships among all endpoints, see the interactive schema documentation.
XSD Schema URL:
http://files.api.gracenote.com/xsd/on_update_videoDescriptorsTaxonomy_3.22.xsd
The XPATH in the table below is relative to: on/videoDescriptorsTaxonomy/taxonomyItem/videoDescriptors/videoDescriptor
| XPATH Element/Attribute | Description | Example |
|---|---|---|
| videoDescriptorId | Video descriptor identifier | GN7ZZYX4F3NN90Y |
| videoDescriptorName | Video descriptor name | ABBA |
| videoDescriptorParentId | Video descriptor parent identifier | GN9V5B4HXZG9X2J |
| typeId | Video descriptor type identifier the descriptor belongs to | GN5K25Z6A1Y4TYJ |
| typeName | Video descriptor type name | Subject - Specific Being / Group |
Important: The update object in VideoDescriptorsTaxonomy endpoint is not an individual descriptor, but rather a taxonomy item carrying a list of descriptors of specific type/category. Furthermore, unlike the other endpoints, taxonomy items in the VDT endpoint do not carry a unique identifier. Instead, each descriptor in the taxonomy item contains a typeId which can be used as a unique identifier for the parent taxonomy item (it is the same on all descriptors in the taxonomy item).
<taxonomyItem updateId="0" updateDate="2024-03-14T22:10:40Z">
<videoDescriptors>
<videoDescriptor>
<videoDescriptorId>GN7ZZYX4F3NN90Y</videoDescriptorId>
<videoDescriptorName>ABBA</videoDescriptorName>
<videoDescriptorParentId>GNB8TG1727QECG3</videoDescriptorParentId> <typeId>GN5K25Z6A1Y4TYJ</typeId>
<typeName>Subject - Specific Being / Group</typeName>
</videoDescriptor>
</videoDescriptors>
</taxonomyItem>
Video Descriptor Types
The Video Descriptors are organized in 16 types/categories (Character, Concept Source, Scenario, Theme, Video Mood, Setting (3 categories), Subject (8 categories), each category containing hierarchies of descriptors up to 4 levels deep, from more generic descriptors (roots) to more nuanced descriptors (leafs). The hierarchy trees are encoded in the videoDescriptorParentId links.
(*) indicates required descriptor types/categories.
Descriptor assignments to Programs carry one of the following numeric weights:
-
5 (significant aspect)
-
7 (major aspect)
-
9 (primary aspect)
Translated Taxonomy
A non-English market client may need a translated taxonomy if they choose to show Video Descriptors on their UI. The translated values are available in the Data Dictionaries and Controlled Vocabulary endpoint. The video descriptors taxonomy is translated into the following languages: Arabic, Chinese (Simplified), Chinese (Traditional), Czech, Danish, Dutch, Filipino, Finnish, French (France), Greek, German, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese (Portugal), Portuguese (Brazil), Romanian, Russian, Spanish (Spain), Swedish, Tamil, Telugu, Thai, Turkish
Video Descriptor Taxonomy Entity Relationship Diagram
The following ERD illustrates the ID relationships for Video Descriptor Taxonomy
Video Descriptor Coverage
Video Descriptors data set was launched in early 2019, and Gracenote currently covers programs based on the customer's catalog and content available in a specific country. We prioritize programs for tagging using various signals such as popularity, Prime time TV programming, Theatrical releases, Historical Box office top grossing programs, and availability across top broadcasters and OTT providers.
Regarding Program coverage:
- Movies (MV records), including Feature Film, Short Film, TV movies are covered.
- TV Shows and Specials (SH records), including Series and Mini-series are covered.
- Episodes and Season level records are not covered.
- For a given Program, all associated TMSIds are tagged with the same descriptors.
- Some of the excluded programming Genres include: Sports, Sports Non-events, Team Event, Weather, Shopping and Adult content.
- Most programs will have between 20-30 Video descriptors tags, although this can vary depending on the nature of the content. Fiction programming (most movies and TV shows) tend to have higher number of tags compared to Documentaries, Reality/Non-Fiction programming.
- Nine new descriptor types were introduced in Q3 2019 with the "Subject Release". Programs tagged before this release do not contain tags from these new descriptor types. Back-tagging is expected to be completed in early 2020. Please contact Gracenote if you need additional information on 'Back-tagging' coverage for "Subject-types".
- There are currently 16 types of Descriptors available in the Taxonomy. Only descriptors applicable to the content is tagged, so it is possible that a program does not have descriptors from all 16 types. For example, the fictional TV show 'Game of Thrones' will not have a "Subject- Specific Event" tag, which is suited for real-life /historical events or the nature documentary 'Planet Earth' will not have "Characters" typically used for fictional content.
Note: If you do have specific use cases that require coverage across excluded Genres or Program Types, please contact your Gracenote Account representative so that we can explore coverage options.
Video Descriptors Types
Video Descriptors are classified into the following types of descriptors:
| Type | Definition |
|---|---|
| Mood | A tone of the work, as expressed through the combination of story, characters, setting, dialog, art direction, cinematography, music, effects, etc. |
| Theme | An abstract concept of human experience that the work addresses |
| Scenario | A specific situation, often personal or interpersonal, that sets the plot into movement, or moves it forward |
| Concept Source | The type of original source material that provided the inspiration or story for the work |
| Character | Actual or fictional being/group relevant to a work, encompassing occupation, personality, relationship, nationality, ethnicity, religion, cultural affinities, physical / mental condition, life stage, etc. |
| Setting - Time | A time period in which all, or a portion, of the plot is set |
| Setting - Place | A type of physical environment in which all, or a portion of, the plot is set - realm, area, specific outdoor or indoor environment |
| Setting - Occasion | A global cultural, religious or national holiday or festival, or transitory personal event addressed in the work |
| Subject – Specific Location | A continent, region, country, state, province, celestial object, planet, solar system, fantasy worlds or supernatural realm noted as a subject of the work |
| Subject - Issue | A mental state, emotion, personal quality or mental or physical condition noted as a subject of the work |
| Subject – Personal Issue | A mental state, emotion, personal quality or mental or physical condition that impact one’s being noted as a subject of the work |
| Subject – Specific Being/Group | An actual, fictional or spiritual person, group or organization noted as a subject the work |
| Subject – Specific Event | An actual, fictional or spiritual event of the past, present or future noted as a subject of the work |
| Subject - Milieu | A well-known combination of place and time, usually with additional explicit or implicit historical or cultural context that is noted as a subject of the work |
| Subject Practice | A professional, vocational, activist, scholarly, religious or artistic pursuit, or other committed endeavor noted as a subject of the work |
| Subject - Activity | A pursuit done for enjoyment, interest, or lifestyle outside of a professional context noted as a subject of the work |
Video Descriptor Weights
Each video descriptor applied to a program is also accompanied by a weighting score. This adds a second dimension of relevancy to Gracenote video descriptors that can be used to further refine content analysis and recommendations. For computational purposes, descriptors will be measured on a 10 point scale, but for editorial simplicity and to discern clearly between the importance of each descriptor, weighting selections will be made on a 5 point scale of 1,3,5,7, and 9. However, today Gracenote editors only use the weights of 5, 7, and 9. This is so as only the most relevant aspects of a work are tagged. The following table further explains what is meant by each weight.
| Weight | Description | Notes |
|---|---|---|
| 1 | Nominal information | Not used today |
| 3 | Minor program aspect | Not used today |
| 5 | Significant program aspect |
Tags anything that is a significant part of the work, but not a primary or major focus. |
| 7 | Major program aspect |
Tags very important details that are not the primary focus of the work. |
| 9 | Primary program aspect | Represents the most important descriptor per type. However, this can vary based on content, and more importantly, the ‘type’ because certain types are more likely to have multiple 9s than others, such as Character and the many Subject types. |
One 9 is required in each type for it to be considered complete. 7s and 5s are applied only when a keyword is considered applicable. This means some types in a given work will just have 9s while others will have 9s and a combination of 7s and 5s. For example, consider the movie Deadpool. For mood the following tags were applied: Visceral, Irreverent, Romantic, Thrilling, and Violent. Deadpool is a movie known for action and comedy so this would be an example when two 9s would be appropriate. In this case, that be Irreverent and Thrilling. From there, this film showcases violence, but that is not the primary focus. So visceral and violent are both 7s. Finally, although this film does focus on romance, it is not a major aspect relative to the other parts. Therefore, Romantic is weighted as 5. Overall, this weighting allows Gracenote to show, which moods are the most important when discussing Deadpool. It is similar to other programs tagged with Thrilling and/ or Irreverent, while also allowing for a different look for content similarity.